/*
 * This file is part of the Sx Framework Library.
 * 
 * Copyright (C) 2013 University of Colorado Denver
 * <min.choi@ucdenver.edu> <shane.transue@ucdenver.edu>
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy 
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
 * copies of the Software, and to permit persons to whom the Software is 
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in 
 * all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
 * DEALINGS IN THE SOFTWARE.
 */
#ifndef SX_PROGRESS_MONITOR_H
#define SX_PROGRESS_MONITOR_H

#include <sxProgressable.h>

namespace Sx {
namespace Task {

/*
 * The ProgressMonitor class has been provided so that for classes that wish
 * to utilize the progressable interface, frequent checks for a null 
 * progressable pointer will be eliminated. The progressable member has to be
 * a pointer since the polymorphism is required for the implementation of the
 * interface. This means that if a progressable is not set in a class that uses
 * a ProgressMonitor, it will simply not be used and still operate correctly.
 *
 * Unfortunately, this ties the interface of this class to the Progressable
 * interface definition; but neither should need to change since progress is
 * usually indicated by a range, value, and a descriptive message. 
 */
class ProgessMonitor {
public:
	ProgessMonitor();
	virtual ~ProgessMonitor();

	/*
	 * Based on the Progressable interface, a progressable implementation can
	 * be provided as the user interface component that displays the progress
	 * of this monitor.
	 */
	void setMonitor(Progressable* progressMonitor);

    /* 
	 * Sets the title of the progressable implementaiton. The provided 
	 * implementation of the Progressable interface determines the 
	 * interpretation of this function.
	 */
	void setTitle(const String& title);
	
	/*
	 * Sets the text of the progressable implementation. The provided 
	 * implementation of the Progressable interface determines the 
	 * interpretation of this function.
	 */
	void setDescription(const String& text);

	/*
	 * Sets the range of values that define the start and end of the progress.
	 * The provided implementation of the Progressable interface determines the 
	 * interpretation of this function.
	 */
	void setRange(unsigned int min, unsigned int max);

	/*
	 * Sets the value of the current progress position. This value must be
	 * between the sepecified range (see setRange(..)). The provided 
	 * implementation of the Progressable interface determines the
	 * interpretation of this function.
	 */
	void setValue(unsigned int value);

	/*
	 * When the operation is complete there may be some functions that need
	 * to occur once the monitored operation is complete. The provided 
	 * implementation of the Progressable interface determines the
	 * interpretation of this function. For example: closing a dialog box.
	 */
	void complete();

	/*
	 * Allows for objects that contain this ProgressMonitor to check for user
	 * interface events that indicate that the operation was canceled. Since
	 * the user interface provides this flag, the object that utilizes this
	 * ProgressMonitor must routinely check to ensure the user has not canceled
	 * the operation. For example:
	 *
	 *  while ( doingOperation) {
	 *    if ( progressMonitor.canceled() == true ) {
	 *      // Memory cleanup...
	 *      // Exit gracefully...
	 *  }
	 */
	bool canceled();

	/*
	 * This function returns the Progressable type associated with this monitor.
	 */
	Progressable* const getMonitor() const;

protected:
	/*
	 * Pointer Ownership: NO
	 *
	 * This pointer should be initialized with the implementation of the 
	 * Progressable interface for displaying the progress of this monitor to
	 * the user. This pointer is not owned by this object and must be managed
	 * separately by the user.
	 */
	Progressable* progressable;
};

}

}

#endif
